Skip to content

Document vm_today and datetime support in calculated fields #1167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
nrichers wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Document vm_today and datetime support in calculated fields #1167

nrichers wants to merge 1 commit into from

Conversation

@nrichers
Copy link
Collaborator

@nrichers nrichers commented Feb 10, 2026 •
edited
Loading

Summary of changes

  • New collapsible example under Calculation field type: "Example — Date arithmetic and vm_today".
  • Table of names available in formulas: vm_today, date, datetime, timedelta, relativedelta.
  • Two example formulas:
    1. Next review date — Approval date + interval by risk tier (Tier 1: +3 months, Tier 2: +6 months, Tier 3: +1 year).
    2. Days remaining — Countdown to next review using vm_today (updates when formula re-runs).
  • Note on behavior: date fields passed in as millisecond timestamps; formula output is string (use .isoformat() for dates).

File touched: site/guide/model-inventory/_field-types.qmd.

Findings from codebase investigation

  • Backend (backend/src/backend/utils/code_executor.py): Execution environment injects vm_today = date.today() and exposes date, datetime, timedelta, relativedelta (and others) into formula scope. Date fields are passed as values that require int(params.x) / 1000 for date.fromtimestamp() (JS/Python timestamp precision difference).
  • Feature history: Implemented in Sprint 63 (Nov 2024), backend PR PR#1003 — Merge main into staging #1004, frontend PR docs: Show model stakeholder updates in model activity #1078. Held from release notes then; dev confirmed ready to document now.
  • No library notebooks reference this — it is a platform UI feature for inventory calculated fields only.
  • Reference: Andres's gist (complex + simple examples) and demo transcript (days-remaining countdown use of vm_today).

How to test

Open deploy preview → Model inventory → Field types → Calculation, expand "Example — Date arithmetic and vm_today" and confirm table + code blocks render.

[sc-7465]

@nrichers nrichers added the internal Not to be externalized in the release notes label Feb 10, 2026
@nrichers
Document vm_today and datetime support in calculated fields
35ddc67 
Add collapsible example for date arithmetic in model inventory
calculation fields: vm_today, date, datetime, timedelta, relativedelta.
Includes next review date and days-remaining countdown examples.
Notes timestamp input and string output behavior.

[sc-7465]
@nrichers nrichers force-pushed the sc-7465/vm-today-datetime-constant branch from 5f917e9 to 35ddc67 Compare February 10, 2026 23:13
@github-actions
Copy link
Contributor

github-actions bot commented Feb 10, 2026

PR Summary

This PR introduces a new section in the documentation for the model inventory fields. The changes add detailed, practical examples on how formulas can leverage date arithmetic and the special variable vm_today for dynamic date calculations. The documentation now includes two main examples:

  1. Next Review Date Calculation: Demonstrates how to compute the next review date by converting a millisecond timestamp into a date, selecting an appropriate review interval based on a risk tier (Tier 1, Tier 2, Tier 3), and outputting the next review date in ISO format. The example also gracefully handles cases where the approval date is missing or an unsupported risk tier is provided.

  2. Days Remaining Countdown: Shows how to calculate the number of days remaining until the next review date. It converts an ISO formatted date back to a date object, computes the difference from the current date (vm_today), and returns the result in a human-readable format.

These enhancements provide users with clear, sample implementations that detail how to work with date and time types within formulas, thereby improving the usability and clarity of the system documentation.

Test Suggestions

  • Verify that the 'Next Review Date' example returns 'N/A' when the 'dmApprovedDate' is empty.
  • Test the formula with valid timestamps for each risk tier to ensure the correct interval is applied and the output matches the expected ISO format.
  • Check that the risk tier not present in the provided dictionary correctly leads to an 'N/A' output.
  • For the 'Days Remaining' example, simulate different values of 'nextReviewDate' relative to 'vm_today' and confirm that the countdown displays the correct number of days.
  • Ensure that the conversion from timestamps to date objects and back to string formats works consistently across different date inputs.

@claude
Copy link

claude bot commented Feb 10, 2026

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@github-actions
Copy link
Contributor

github-actions bot commented Feb 10, 2026

Lighthouse check results

⚠️ WARN: Average accessibility score is 0.87 (required: >0.9) — Check the workflow run

Show Lighthouse scores

Folder depth level checked: 0

Commit SHA: 0322276

Modify the workflow to check a different depth:

  • 0: Top-level navigation only — /index.html, /guide/guides.html, ...
  • 1: All first-level subdirectories — /guide/.html, /developer/.html, ...
  • 2: All second-level subdirectories — /guide/attestation/*.html, ...
Page Accessibility Performance Best Practices SEO
/developer/validmind-library.html 0.85 0.68 1.00 0.82
/get-started/get-started.html 0.85 0.69 1.00 0.73
/guide/guides.html 0.85 0.69 1.00 0.82
/index.html 0.93 0.65 1.00 0.82
/releases/all-releases.html 0.86 0.69 1.00 0.73
/support/support.html 0.91 0.61 1.00 0.82
/training/training.html 0.85 0.69 0.96 0.73

@github-actions
Copy link
Contributor

github-actions bot commented Feb 10, 2026

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

internal Not to be externalized in the release notes

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nrichers